home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 21 / CU Amiga Magazine's Super CD-ROM 21 (1998)(EMAP Images)(GB)[!][issue 1998-04].iso / CUCD / Programming / MCC_SettingsWindow / Developer / Autodocs / MCC_SettingsWindow.doc
Text File  |  1997-12-20  |  16KB  |  509 lines
  1. TABLE OF CONTENTS
  2.  
  3. SettingsWindow.mcc/SettingsWindow.mcc
  4. SettingsWindow.mcc/Types
  5. SettingsWindow.mcc/MUIA_SettingsWindow_Changed
  6. SettingsWindow.mcc/MUIA_SettingsWindow_PortDirectly
  7. SettingsWindow.mcc/MUIA_SettingsWindow_TestButton
  8. SettingsWindow.mcc/MUIA_SettingsWindow_TestMode
  9. SettingsWindow.mcc/MUIM_SettingsWindow_Cancel
  10. SettingsWindow.mcc/MUIM_SettingsWindow_CustomInsert
  11. SettingsWindow.mcc/MUIM_SettingsWindow_GetItem
  12. SettingsWindow.mcc/MUIM_SettingsWindow_KillNotify
  13. SettingsWindow.mcc/MUIM_SettingsWindow_KillNotifyObj
  14. SettingsWindow.mcc/MUIM_SettingsWindow_Init
  15. SettingsWindow.mcc/MUIM_SettingsWindow_LastSaved
  16. SettingsWindow.mcc/MUIM_SettingsWindow_Load
  17. SettingsWindow.mcc/MUIM_SettingsWindow_NNSetItem
  18. SettingsWindow.mcc/MUIM_SettingsWindow_Notify
  19. SettingsWindow.mcc/MUIM_SettingsWindow_Reset
  20. SettingsWindow.mcc/MUIM_SettingsWindow_Restore
  21. SettingsWindow.mcc/MUIM_SettingsWindow_Save
  22. SettingsWindow.mcc/MUIM_SettingsWindow_SaveAs
  23. SettingsWindow.mcc/MUIM_SettingsWindow_SetItem
  24. SettingsWindow.mcc/MUIM_SettingsWindow_Store
  25. SettingsWindow.mcc/MUIM_SettingsWindow_Use
  26. SettingsWindow.mcc/SettingsWindow.mcc
  27.  
  28. SettingsWindow.mcc is a subclass of Window.mui that allows you to easily
  29. manage your programs settings. There is a notification mechanism similar to
  30. that of MUI to react on changing settings. A row of buttons and a menu let
  31. the user have the standard save, use, load functions.
  32. The SettingsWindowObject can be created similar to an ordinary WindowObject,
  33. but without menustrip. The object you supply as root object will be put in a
  34. vertical group with a row of buttons (save, use [, test], cancel). The
  35. objects in the SettingsWindow have nothing to do with the settings handling
  36. directly - you must explicitly specify this using MUIM_SettingsWindow_Init.
  37. SettingsWindow.mcc/Types
  38.  
  39. Something about the types you can use with MUIM_SettingsWindow_Init:
  40.  
  41. SWIT_STANDARD:
  42.     Used for "4 bytes" attributes such as BOOL or ULONG, where you can get()
  43.     the value directly, not a pointer to it.
  44.  
  45. SWIT_STRING:
  46.     The attribute is a string pointer (e.g. MUIA_String_Contents).
  47.  
  48. SWIT_STRUCT:
  49.     The attribute can be a pointer to a structure or any data with a fixed
  50.     size (e.g. MUIA_Pendisplay_Spec).
  51.  
  52. SWIT_COMPLEX:
  53.     The attribute is a pointer to a well defined structure that can contain
  54.     pointers to further data that can contain pointers... and so on. Invoking
  55.     MUIM_SettungsWindow_Init you must supply a pointer to an array of UWORD
  56.     describing this data format for the size parameter.
  57.     This array contains exactly one type specified by the following BNF:
  58.  
  59.     type    := simple / array / pointer / struct / string
  60.  
  61.     simple  := "SWIS_BYTE" / "SWIS_WORD" / "SWIS_LONG" / "SWIS_EVEN"
  62.                / "SWIS_EVEN4" / <number of range 1...32767>
  63.  
  64.     array   := "SWIS_ARRAY" "," <number of range 0...65534>  "," type
  65.  
  66.     pointer := "SWIS_POINTER" "," type
  67.  
  68.     struct  := "SWIS_STRUCT" "," types "SWIS_END"
  69.  
  70.     string  := "SWIS_STRING" "," count
  71.  
  72.     count   := "-1" / <number of range 0...65534>
  73.  
  74.     types   := type "," ftypes
  75.  
  76.     ftypes  := types / ""
  77.  
  78.  
  79.     type    - a simple type, an array, a pointer, a structure or a string
  80.  
  81.     simple  - one of the simple types byte, word, longword, even address,
  82.               address divisible by four or a number of bytes
  83.  
  84.     array   - number of elements of the same type
  85.  
  86.     pointer - pointer to a type
  87.  
  88.     struct  - structure of various types
  89.  
  90.     string  - chain of count (terminated by 0 if -1) characters
  91.  
  92.  
  93.     Example:
  94.  
  95.     static UWORD testit_des[]=
  96.     {
  97.         SWIS_STRUCT,
  98.             SWIS_POINTER, SWIS_STRING,-1,
  99.             SWIS_LONG,
  100.             SWIS_LONG,
  101.             SWIS_POINTER, SWIS_STRING,-1,
  102.             SWIS_END
  103.     };
  104.  
  105.     describes a structure like the following:
  106.  
  107.     struct testit
  108.     {
  109.         STRPTR str1;
  110.         ULONG  u1;
  111.         ULONG  u2;
  112.         STRPTR str2;
  113.     };
  114.  
  115.  
  116. SWIT_(N)LISTSTANDARD
  117.     The object is a (N)List of "4 byte"-entries.
  118.  
  119. SWIT_(N)LISTSTRING
  120.     The object is a (N)List of string pointers.
  121.  
  122. SWIT_(N)LISTSTRUCT
  123.     The object is a (N)List of pointers to a structure or any data with a
  124.     fixed size.
  125.  
  126. SWIT_(N)LISTCOMPLEX
  127.     The object is a (N)List of pointers to rather complex structures (take a
  128.     look at SWIT_COMPLEX). Invoking MUIM_SettungsWindow_Init you must supply
  129.     a pointer to an array of UWORD describing this data format for the size
  130.     parameter.
  131.  
  132. SWIT_(N)LISTCUSTOM
  133.     Similar to SWIT_(N)LISTCOMPLEX, but the lists construct hook doesn't
  134.     simply copies the supplied data. That's why instead of
  135.     MUIM_(N)List_Insert MUIM_SettingsWindow_CustomInsert is invoked.
  136. SettingsWindow.mcc/MUIA_SettingsWindow_Changed
  137.  
  138.    NAME
  139.        MUIA_SettingsWindow_Changed -- [.SGN], BOOL
  140.  
  141.    FUNCTION
  142.        This attribute is set to TRUE, whenever the current settings have been
  143.        changed. This is quite useful, if you don't like to react on each
  144.        modified item, but on a group of items, e.g. dimensions and position
  145.        of an open window.
  146. SettingsWindow.mcc/MUIA_SettingsWindow_PortDirectly
  147.  
  148.    NAME
  149.        MUIA_SettingsWindow_PortDirectly -- [.SGN], BOOL
  150.  
  151.    FUNCTION
  152.        This attribute affects the import/export behaviour.
  153.        Set to FALSE the stored settings item values are im-/exported, the
  154.        attributes of the objects you gave MUIM_SettingsWindow_Init are used
  155.        otherwise (e.g. in MUIM_SettingsWindow_Load and
  156.        MUIM_SettingsWindow_SaveAs).
  157.  
  158.        I can't imagine any reason why you should need this attribute.
  159. SettingsWindow.mcc/MUIA_SettingsWindow_TestButton
  160.  
  161.    NAME
  162.        MUIA_SettingsWindow_TestButton -- [I...], BOOL
  163.  
  164.    FUNCTION
  165.        Enable or disable the "Test" button. Defaults to FALSE.
  166. SettingsWindow.mcc/MUIA_SettingsWindow_TestMode
  167.  
  168.    NAME
  169.        MUIA_SettingsWindow_TestMode -- [.SGN], BOOL
  170.  
  171.    FUNCTION
  172.        Setting this attribute to TRUE turns on the test mode, changes made
  173.        affect the application as long as the settings window stays open.
  174.        Setting it to FALSE has no further effect.
  175.  
  176.        Your application does not have to care wether it's in test mode or
  177.        not. Since the MUIM_SettingsWindow_Store method is called when
  178.        MUIA_SettingsWindow_TestMode is set to TRUE (e.g. when the user hits
  179.        the "Test" button), all settings will affect the application the same
  180.        way using or saving would do. The only difference is that the
  181.        settings window stays open and the user has the ability to cancel
  182.        what he has done.
  183. SettingsWindow.mcc/MUIM_SettingsWindow_Cancel
  184.  
  185.    NAME
  186.        MUIM_SettingsWindow_Cancel
  187.  
  188.    SYNOPSIS
  189.        DoMethod(obj,MUIM_SettingsWindow_Cancel);
  190.  
  191.    FUNCTION
  192.        Close the settings window and call MUIM_SettingsWindow_Reset to reset
  193.        all attributes concerned.
  194.  
  195.        This method is called when the user hits the "Cancel" button or
  196.        selects the window close gadget or the "Quit" menu item. Usually
  197.        that's something you don't have to care for.
  198. SettingsWindow.mcc/MUIM_SettingsWindow_CustomInsert
  199.  
  200.    NAME
  201.        MUIM_SettingsWindow_CustomInsert
  202.  
  203.    SYNOPSIS
  204.        DoMethod(obj,MUIM_SettingsWindow_CustomInsert,APTR *Entries,
  205.            ULONG Count, ULONG Pos);
  206.  
  207.    FUNCTION
  208.        Within MUIM_SettingsWindow_Reset the settings window object invokes
  209.        this method on the concerned object of settings items of type
  210.        SWIT_(N)LISTCUSTOM.
  211.        You have to implement this method in a subclass, if your list
  212.        objects construct hook doesn't simply copies the supplied data.
  213.  
  214.    INPUTS
  215.        The parameters are the same as used by MUIM_(N)List_Insert.
  216.  
  217.    NOTE
  218.        This method has to return TRUE. This is not important in the current
  219.        version, but may become vital for future extensions.
  220.  
  221.    SEE ALSO
  222.        MUIM_SettingsWindow_Init
  223. SettingsWindow.mcc/MUIM_SettingsWindow_GetItem
  224.  
  225.    NAME
  226.        MUIM_SettingsWindow_GetItem
  227.  
  228.    SYNOPSIS
  229.        DoMethod(obj,MUIM_SettingsWindow_GetItem,ULONG ID, ULONG *Storage);
  230.  
  231.    FUNCTION
  232.        The function is equivalent to that of OM_GET.
  233.  
  234.    INPUTS
  235.        ID      - ID of the settings item you want to get.
  236.  
  237.        Storage - pointer to the space where MUIM_SettingsWindow_GetItem
  238.                  shall store the data.
  239.  
  240.    SEE ALSO
  241.        MUIM_SettingsWindow_Init, MUIM_SettingsWindow_Notify,
  242.        MUIM_SettingsWindow_SetItem
  243. SettingsWindow.mcc/MUIM_SettingsWindow_KillNotify
  244.  
  245.    NAME
  246.        MUIM_SettingsWindow_KillNotify
  247.  
  248.    SYNOPSIS
  249.        DoMethod(obj,MUIM_SettingsWindow_KillNotify,ULONG TrigID);
  250.  
  251.    FUNCTION
  252.        The function is equivalent to that of MUIM_KillNotify.
  253.  
  254.    INPUTS
  255.        TrigID  - ID of the settings item you want to remove a notification
  256.                  handler from.
  257.  
  258.    SEE ALSO
  259.        MUIM_SettingsWindow_KillNotifyObj, MUIM_SettingsWindow_Notify,
  260.        MUIM_SettingsWindow_SetItem
  261. SettingsWindow.mcc/MUIM_SettingsWindow_KillNotifyObj
  262.  
  263.    NAME
  264.        MUIM_SettingsWindow_KillNotifyObj
  265.  
  266.    SYNOPSIS
  267.        DoMethod(obj,MUIM_SettingsWindow_KillNotifyObj,ULONG TrigID,
  268.            Object *DestObj);
  269.  
  270.    FUNCTION
  271.        The function is equivalent to that of MUIM_KillNotifyObj.
  272.  
  273.    INPUTS
  274.        TrigID  - ID of the settings item you want to remove a notification
  275.                  handler from.
  276.  
  277.        DestObj - the object the notification method should be performed at.
  278.  
  279.    SEE ALSO
  280.        MUIM_SettingsWindow_KillNotify, MUIM_SettingsWindow_Notify,
  281.        MUIM_SettingsWindow_SetItem
  282. SettingsWindow.mcc/MUIM_SettingsWindow_Init
  283.  
  284.    NAME
  285.        MUIM_SettingsWindow_Init
  286.  
  287.    SYNOPSIS
  288.        DoMethod(obj,MUIM_SettingsWindow_Init,Object *Obj1, ULONG Attr1,
  289.            ULONG Type1, ULONG Size1, ULONG ID1, /* ... */);
  290.  
  291.    FUNCTION
  292.        Initialize the settings window object. You have to define which
  293.        attribute of which object of which type, size and id you want to
  294.        get managed by your settings window object.
  295.        The method calls MUIM_SettingsWindow_Store to get valid values and
  296.        after that it tries to load the current settings with
  297.        MUIM_SettingsWindow_Load.
  298.  
  299.    INPUTS
  300.        Obj1    - pointer to an object that contains the attribute that shall
  301.                  be managed by this settings window object.
  302.  
  303.        Attr1   - TagID of the attribute, ignored for SWIT_(N)LISTxxx.
  304.  
  305.        Type1   - type of the attribute/object, take a look at the type
  306.                  section
  307.  
  308.        Size1   - size of the attribute for SWIT_STRING and SWIT_STRUCT;
  309.                  size of the list entries for SWIT_(N)LISTSTRING and
  310.                  SWIT_(N)LISTSTRUCT;
  311.                  pointer to a description array for SWIT_([N]LIST)COMPLEX and
  312.                  SWIT_(N)LISTCUSTOM;
  313.                  ignored for SWIT_STANDARD and SWIT_(N)LIST_STANDARD.
  314.  
  315.        ID      - ID of the settings item used to access the item via
  316.                  MUIM_SettingsWindow_SetItem/GetItem/Notify, but it's used to
  317.                  save the item, too. So don't give another object the same
  318.                  MUIA_ObjectID.
  319.  
  320.        The parameters for the next settings item follow. There can be as
  321.        many items as you want; a NULL object pointer indicates the end of the
  322.        array.
  323.  
  324.  
  325.    SEE ALSO
  326.        MUIM_SettingsWindow_GetItem, MUIM_SettingsWindow_Notify,
  327.        MUIM_SettingsWindow_SetItem
  328. SettingsWindow.mcc/MUIM_SettingsWindow_LastSaved
  329.  
  330.    NAME
  331.        MUIM_SettingsWindow_LastSaved
  332.  
  333.    SYNOPSIS
  334.        DoMethod(obj,MUIM_SettingsWindow_LastSaved);
  335.  
  336.    FUNCTION
  337.        Load the last saved settings.
  338.  
  339.        This method is called when the user selects the "Last Saved" menu
  340.        item. Usually that's something you don't have to care for.
  341. SettingsWindow.mcc/MUIM_SettingsWindow_Load
  342.  
  343.    NAME
  344.        MUIM_SettingsWindow_Load
  345.  
  346.    SYNOPSIS
  347.        DoMethod(obj,MUIM_SettingsWindow_Load);
  348.  
  349.    FUNCTION
  350.        Pop up an ASL requester where the user can select the settings he wants
  351.        to load.
  352.  
  353.        This method is called when the user selects the "Load" menu item.
  354.        Usually that's something you don't have to care for.
  355. SettingsWindow.mcc/MUIM_SettingsWindow_NNSetItem
  356.  
  357.    NAME
  358.        MUIM_SettingsWindow_NNSetItem
  359.  
  360.    SYNOPSIS
  361.        DoMethod(obj,MUIM_SettingsWindow_NNSetItem,ULONG ID, ULONG Value);
  362.  
  363.    FUNCTION
  364.        The function is equivalent to that of MUIM_NoNotifySet.
  365.  
  366.    INPUTS
  367.        ID      - ID of the settings item you want to set.
  368.  
  369.        Value   - value to set the item to.
  370.  
  371.    SEE ALSO
  372.        MUIM_SettingsWindow_GetItem, MUIM_SettingsWindow_Notify
  373.        MUIM_SettingsWindow_SetItem
  374. SettingsWindow.mcc/MUIM_SettingsWindow_Notify
  375.  
  376.    NAME
  377.        MUIM_SettingsWindow_Notify
  378.  
  379.    SYNOPSIS
  380.        DoMethod(obj,MUIM_SettingsWindow_Notify,ULONG TrigID, ULONG TrigValue,
  381.            Object *DestObj, ULONG FollowParams, /* ... */);
  382.  
  383.    FUNCTION
  384.        The function is equivalent to that of MUIM_Notify.
  385.  
  386.    INPUTS
  387.        TrigID       - ID of the settings item that triggers the notification.
  388.  
  389.        TrigValue    - value that triggers the notification,
  390.                       MUIV_EveryTime is supported.
  391.  
  392.        DestObj      - object on which to perform the notification method,
  393.                       MUIV_Notify_Self, MUIV_Notify_Window and
  394.                       MUIV_Notify_Application are supported.
  395.  
  396.        FollowParams - number of the following parameters.
  397.  
  398.        MUIV_TriggerValue and MUIV_NotTriggerValue are supported for the
  399.        following parameters.
  400.  
  401.    RESULT
  402.        Since it needs to allocate memory, this method can fail. It returns
  403.        TRUE if successful, FALSE otherwise.
  404.  
  405.    SEE ALSO
  406.        MUIM_SettingsWindow_GetItem, MUIM_SettingsWindow_NNSetItem
  407.        MUIM_SettingsWindow_SetItem
  408. SettingsWindow.mcc/MUIM_SettingsWindow_Reset
  409.  
  410.    NAME
  411.        MUIM_SettingsWindow_Reset
  412.  
  413.    SYNOPSIS
  414.        DoMethod(obj,MUIM_SettingsWindow_Reset);
  415.  
  416.    FUNCTION
  417.        Set all attributes to the values the settings window object has
  418.        stored. This method is called from MUIM_SettingsWindow_Cancel.
  419.  
  420.        Usually you don't need to call it.
  421. SettingsWindow.mcc/MUIM_SettingsWindow_Restore
  422.  
  423.    NAME
  424.        MUIM_SettingsWindow_Restore
  425.  
  426.    SYNOPSIS
  427.        DoMethod(obj,MUIM_SettingsWindow_Restore);
  428.  
  429.    FUNCTION
  430.        Load the last used settings.
  431.  
  432.        This method is called when the user selects the "Restore" menu
  433.        item. Usually that's something you don't have to care for.
  434. SettingsWindow.mcc/MUIM_SettingsWindow_Save
  435.  
  436.    NAME
  437.        MUIM_SettingsWindow_Save
  438.  
  439.    SYNOPSIS
  440.        DoMethod(obj,MUIM_SettingsWindow_Save);
  441.  
  442.    FUNCTION
  443.        Save the current settings to "ENVARC:" and call
  444.        MUIM_SettingsWindow_Use.
  445.  
  446.        This method is called when the "Save" button was pressed. Usually
  447.        that's something you don't have to care for.
  448. SettingsWindow.mcc/MUIM_SettingsWindow_SaveAs
  449.  
  450.    NAME
  451.        MUIM_SettingsWindow_SaveAs
  452.  
  453.    SYNOPSIS
  454.        DoMethod(obj,MUIM_SettingsWindow_SaveAs);
  455.  
  456.    FUNCTION
  457.        Pop up an ASL requester where the user can select a file he wants to
  458.        save the current settings as.
  459.  
  460.        This method is called when the user selects the "Save As" menu item.
  461.        Usually that's something you don't have to care for.
  462. SettingsWindow.mcc/MUIM_SettingsWindow_SetItem
  463.  
  464.    NAME
  465.        MUIM_SettingsWindow_SetItem
  466.  
  467.    SYNOPSIS
  468.        DoMethod(obj,MUIM_SettingsWindow_SetItem,ULONG ID, ULONG Value);
  469.  
  470.    FUNCTION
  471.        The function is equivalent to that of MUIM_Set.
  472.  
  473.    INPUTS
  474.        ID      - ID of the settings item you want to set.
  475.  
  476.        Value   - value to set the item to.
  477.  
  478.    SEE ALSO
  479.        MUIM_SettingsWindow_GetItem, MUIM_SettingsWindow_NNSetItem
  480.        MUIM_SettingsWindow_Notify
  481. SettingsWindow.mcc/MUIM_SettingsWindow_Store
  482.  
  483.    NAME
  484.        MUIM_SettingsWindow_Store
  485.  
  486.    SYNOPSIS
  487.        DoMethod(obj,MUIM_SettingsWindow_Store);
  488.  
  489.    FUNCTION
  490.        Get all attributes and store it. This method is called from
  491.        MUIM_SettingsWindow_Use.
  492.  
  493.        Usually you don't need to call it.
  494. SettingsWindow.mcc/MUIM_SettingsWindow_Use
  495.  
  496.    NAME
  497.        MUIM_SettingsWindow_Use
  498.  
  499.    SYNOPSIS
  500.        DoMethod(obj,MUIM_SettingsWindow_Use);
  501.  
  502.    FUNCTION
  503.        Call MUIM_SettingsWindow_Store to store the changes, close the
  504.        settings window and save the current settings to "ENV:".
  505.  
  506.        This method is called when the user hits the "Use" button. Usually
  507.        that's something you don't have to care for.
  508.  
  509.